home *** CD-ROM | disk | FTP | other *** search
/ BBS in a Box 9 / AMUG BBS in a Box Volume IX (August 1993) (MacWizards).iso / Files / Util / L / Locare 1.9 SW.cpt / Locare 1.9 SW / Locare 1.9 SW Documentation next >
Encoding:
Text File  |  1987-07-25  |  11.2 KB  |  301 lines  |  [TEXT/KAHL]
  1. Locare 1.9 Documentation
  2.  
  3. Locare was (and will always be) written by Raymond Lau.
  4. Copyright 1987, Raymond Lau.
  5. Portions copyright 1986, THINK Technologies, Inc.
  6.  
  7. June 24,1987
  8.  
  9.  
  10. Locare is a lost file finder FKEY patterned after PCPC's Eureka! and
  11. increasingly so, Apple's FileFinder.
  12.  
  13.  
  14. IMPORTANT: USE ONLY WITH A HFS EQUIPPED SYSTEM.  IF YOU RUN IT ON A MFS
  15. SYSTEM (128K OR 512K W/O HD 20 FILE), IT *WILL* RESULT IN A SYSTEM ERROR.
  16. Be forewarned!  (It's quite useless on a MFS system, so why bother…)
  17.  
  18.  
  19.  
  20.  
  21.  
  22. Distribution:
  23.  
  24. This version of Locare (1.8 Shareware Demo) may be distributed freely as
  25. long as it's distributed w/o financial compensation and not as an
  26. incentive to buy another product and as long as it's distributed with this
  27. doc file.
  28.  
  29. Usage/Shareware:
  30.  
  31. You may try this version of Locare out for a period of 15 days.  If you
  32. decide that you like it or find it useful, send the author (that's me I
  33. hope!) $10 with a disk and a self addressed stamped envelope for the latest
  34. version or send $15 and I'll you a s/s disk.
  35. Any customer of any of my previous products is entitled to a $3 discount.
  36.  
  37. Your first (and possibly 2nd/3rd depending on Locare's maturity) update is
  38. on me.  All I ask is that you return my disk.
  39. Other updates are available for free if you send a disk and sase.  Or send
  40. $5... 
  41.  
  42. Remember, I need you to make this method of distribution work.  As long as
  43. there's some response, I will support the product whenever I can see a
  44. possible improvement or whenever a reasonable one is suggested.  If there
  45. is no response, I'd assume no one finds such a product useful.  If you find
  46. it useful, register.  If not, don't.  Don't wait for someone else to do it.
  47. (That wait will last until eternity.)
  48.  
  49. Raymond Lau
  50. 100-04 70 Ave.
  51. Forest Hills, NY 11375
  52.  
  53.  
  54. Installation:
  55.  
  56.  
  57. To install Locare, use FKEY Mgr, FKEY Installer or a resource editor.  I
  58. suggest the use of FKEY Mgr since it's as easy to use as Apple's Font/DA
  59. Mover.
  60. Locare comes set as FKEY number 8, however, it may be renumbered at will.
  61.  
  62.  
  63. Operation:
  64.  
  65. Type in a part of the name of the file you are searching for.
  66. Locare will search for all files containing what you typed
  67. and display them one by one with each click of the "Find!" button.  If
  68. you wish to limit the match to the start or end of the file name, click on
  69. the appropriate button.  Locare will default to the first mounted volume,
  70. which is usually the hard disk you booted up with (assuming you are using a
  71. hd).  If you wish to search on a separate volume, click on the drive
  72. button.  Some info (and an icon) about the volume is displayed.  Icons are
  73. not shown for offline volumes, but info such as name, used, free, are shown.
  74. You ARE allowed to search an ejected ("Offline") volume, but you
  75. will be prompted to insert that disk.  You may cancel such a request by
  76. typing command-period.
  77.  
  78. The "at beginning/anywhere/at end" radio boxes tell which part of the
  79. filename Locare will compare against the search string.
  80.  
  81. The find only files modified before/after/anytime should be self
  82. explanatory.  Enter the month/day/year into the boxes.  WARNING: Invalid dates
  83. will be interpreted in strange manners.  The date Locare sees will always
  84. be displayed once Find (or return) is selected.
  85.  
  86. The radio buttons marked "all types/appls/other/type" are used to filter files
  87. by file type.  All includes everything.  Appls include only applications.
  88. Other includes documents, various support and system files, etc.  (non-APPL)
  89. Type allows you to specify which single type you want Locare to see.
  90. Some common file types include:
  91.  
  92.     TEXT - text only file.
  93.     WORD - MacWrite file.
  94.     PNTG - MacPaint (also FullPaint) file.
  95.     FKEY - FKEYs
  96.     DFIL - Font/DA Mover DA File
  97.     SPTG - SuperPaint file.
  98.     XLBN - Excel file.
  99.     PICT - MacDraw PICT file.
  100.     nX^d - WriteNow file.
  101.  
  102. File types are case sensitive and must be either 4 characters long or
  103. empty.  If you enter more than 4 chars, Locare will cut off all chars after
  104. the first 4.  If you enter less, Locare will assume you meant an empty
  105. file type.  Spaces are valid characters.
  106.  
  107. The radio buttons marked any/creator are used to filter files by creator.
  108. If any is selected, such filtering is deactivated.  If creator is selected,
  109. only files matching the creator entered in the box below it will be
  110. displayed.  Rules for file types also apply to file creators.  Some
  111. common creators are:
  112.  
  113.     MACA - MacWrite
  114.     nX^n - WriteNow
  115.     XCEL - Excel
  116.     PANT - FullPaint
  117.     CRDW - Cricket Draw
  118.     MDRW - MacDraw
  119.     SPNT - SuperPaint
  120.     ALD2 - PageMaker 2.0
  121.     MRSN - Ready,Set,Go! 3
  122.  
  123. (Note: Many applications are capable of opening files created by other
  124. applications...ex: FullPaint can open MacPaint files.  Setting the
  125. creator filtering to a certain creator won't show files created by
  126. other applications.  In our ex, this means setting creator to PANT won't
  127. show files created by MacPaint.)
  128.     
  129.  
  130. A found file may be deleted.  WARNING: The delete is done at the click of
  131. the mouse.  No warning dialog...yet.
  132.  
  133. A found file may be locked or unlocked.  Locking a file prevents it from
  134. being modified or deleted without first unlocking it…a safety pin of sorts.
  135.  
  136. A found file's GetInfo comments will also be displayed.  It may take
  137. a while for Locare to find these comments on large volumes bec. it has
  138. to find and open the Desktop file.  If your cache is activated (via
  139. Control Panel), the search will be greatly shorten the next time a file
  140. is found on the same volume in the same application.
  141. If the file and volume are both unlocked, you may also modify
  142. these comments or add them.  They will be written to disk when you change
  143. a search parameter, continue searching or close Locare.
  144.  
  145. (Please note:  Comments are supported for HFS volumes only.)
  146.  
  147. Locare also provides a "Preview" hook.  For more information on this hook,
  148. refer to the section towards the end of this file.
  149.  
  150.  
  151. When Locare is closed, it will set the folder in the SFGetFile
  152. ("minifinder") box to the one in which the last file was found.  If you
  153. launched Locare on top of such a box, the folder won't be changed by
  154. Locare.  If you hold the shift key down when you close Locare
  155. (shift-cmd-period or shift-click close box), Locare won't change the
  156. SFGetFile folder.  When closed, Locare will also saved the settings used
  157. in this search (string,location,modified time, etc).  The next time Locare
  158. is opened, it'll read these settings.  These settings are stored in a
  159. file called "Locare Defaults" in the current system folder.  Apple has
  160. documented a potential bug with the way Locare uses BootDrive to find
  161. the System folder.  I haven't been able to reproduce this bug, so I didn't
  162. bother implementing Apple's workaround (which would increase Locare's size)
  163. If you find that Locare startes creating the Locare Defaults in any folder
  164. but the System folder, tell me.
  165.  
  166.  
  167. Keyboard Shortcuts:
  168.  
  169. Return key is the same as clicking on the Find! button EXCEPT when you're
  170.     editing comments, in which case a return is a return…  In such a case,
  171.     shift-return or command-return will be the same as Find! (cont. search)
  172. Command-tab or Shift-tab is the same as clicking on the Drive button.
  173. Tab moves from one edit box to the next.
  174. Command-period is the same as closing Locare except when you are prompted
  175.     for a disk, in which case, it will abort the search then.
  176.  
  177.  
  178. Known bugs:
  179.  
  180. Locare's incompatibility with Switcher 5.1 has been circuvented at the
  181. cost of not being able to run FKEYs on top of Locare and not sending
  182. Desk Accessories their accRun calls.
  183.  
  184.  
  185.  
  186.  
  187. Planned additions:
  188.  
  189. Possibly a list of files found.
  190. A search all mounted volumes.
  191. A search all online volumes.
  192. Better error checking.
  193.  
  194.  
  195. I do not plan to add wildcard capabilities...personally I don't see any need
  196. for it.  If you differ with me on this, tell me...
  197.  
  198. Your comments on these ideas and your suggestions are welcomed (as are
  199. bug reports...after all, nothing is bug free.)
  200.  
  201.  
  202.  
  203. Preview Hook
  204.  
  205. Locare provides a generic way to add external options to deal with a found
  206. file.  The main purpose of this hook is to add an option to preview files
  207. found.  Preview functions will be implemented in the future by myself, or
  208. other programmers.  Locare will search the system folder for these preview
  209. functions.  To install them, just drag them into the system folder.  The
  210. number of preview functions supported is limited only by memory, but
  211. performance will suffer as more and more of them are added.  If a preview
  212. function exists for the type of file found, the preview button will be
  213. enabled.
  214. I've devised this general method of adding a preview option to address the
  215. fact that different people deal with different types of files.  One would
  216. merely obtain and install those preview functions one desires.
  217. For those interested in writing preview functions, refer to the Inside
  218. Locare section at the very end of this file.
  219.  
  220. Included is a very BASIC 'TEXT' file hook.  It is fully functional, but
  221. leaves much to be desired.
  222.  
  223.  
  224. GEnie:RAYLAU
  225. CIS:76174,2617
  226. Delphi: RAYMONDLAU
  227.  
  228.  
  229. "INSIDE LOCARE"
  230.  
  231. Locare provides a hook for the Preview function.  Only those interested in
  232. implementing their own hooks (or the curious) will need to read this
  233. section.
  234.  
  235. When Locare is opened, Locare will search the folder the active System file
  236. is in (the System folder).  When it encounters a file of type 'LcPw'
  237. (creator doesn't matter), it will open the file.  The file must contain
  238. exactly two resources:
  239.  
  240. Type:LcPw
  241. ID:0 (zero)
  242. numTypes: INTEGER { total number of types supported by this hook - 2 bytes }
  243. Type: OSType { X numTypes...  file types supported by this hook } 
  244. .
  245. .
  246. .
  247.  
  248.  
  249. Type:LcPw
  250. ID:1
  251. Pure code resource of:
  252.  
  253.     PROCEDURE myHook(hookInfo: PreviewRecPtr)
  254.     
  255.     TYPE PreviewRecPtr = ^PreviewRec;
  256.     PreviewRec = 
  257.     RECORD
  258.         version:    CHAR;
  259.         message:    CHAR;
  260.         volume:        INTERGER;
  261.         directory:    LONGINT;
  262.         index:        INTEGER
  263.     END;
  264.  
  265.  
  266. version is currently 1.
  267. message is set to 0 on entry.
  268. volume is the volume reference number on which the file is located.  A
  269.     volume reference number is always given, never a working dir.
  270. directory is the directory id in which the file is located.
  271. index is the index for use in PBGetCatInfo to the file.
  272.  
  273. It is up to the procedure to determine what file type the file is, etc. and
  274. to clean up after itself.  It need not save/restore the GrafPort.
  275.  
  276. The proc will set message to 1 if it wants info on the file redisplayed.
  277. This will usually be the case.
  278. The proc will set message to 0 if it doesn't want the info displayed.  It's
  279. hard to conceive of such a case...but an ex. is the delete function...
  280. though I don't see why a hook should implement it.
  281. Other message numbers shouldn't be used...they may serve other functions
  282. in the future.
  283.  
  284. The proc may not destroy the record whose pointer is passed to it.  This
  285. record will be handled by Locare.  The proc is free to modify its fields
  286. since only the message field will be used by Locare.  The proc may not
  287. assume anything about the future length of the record.  All records with
  288. version of 1 will have the above format.  Future records may be supersets
  289. of the current one and will have versions of 2,3,4, etc...
  290.  
  291. The number of file type hooks supported is limited only by memory, but
  292. high numbers will slow down searches.
  293.  
  294. If two hooks exist for the same type, the first installed hook will preside.
  295. (Files are searched in alphabetical order.)
  296.  
  297. I hope you share your preview hooks with the rest of the Mac community.
  298.  
  299. REMEMBER: You'll be running within a FKEY environment.  For compatibility with
  300. Switcher, use GetOSEvent instead of GNE...(I've learned the hard way.)
  301.